github.com/hyperion-hyn/go-ethereum@v2.4.0+incompatible/docs/Getting Started/api.md (about)

     1  
     2  # API
     3  
     4  ## Privacy APIs
     5  
     6  #### eth.sendTransaction
     7  
     8  __To support private transactions in Quorum, the `web3.eth.sendTransaction(object)` API method has been modified.__
     9  
    10  ```js
    11  web3.eth.sendTransaction(transactionObject [, callback])
    12  ```
    13  
    14  Sends a transaction to the network.
    15  
    16  ##### Parameters
    17  
    18  1. `Object` - The transaction object to send:
    19      - `from`: `String` - The address for the sending account. Uses the `web3.eth.defaultAccount` property, if not specified.
    20      - `to`: `String` - (optional) The destination address of the message, left undefined for a contract-creation transaction.
    21      - `value`: `Number|String|BigNumber` - (optional) The value transferred for the transaction in Wei, also the endowment if it's a contract-creation transaction.
    22      - `gas`: `Number|String|BigNumber` - (optional, default: To-Be-Determined) The amount of gas to use for the transaction (unused gas is refunded).
    23      - <strike>`gasPrice`: `Number|String|BigNumber` - (optional, default: To-Be-Determined) The price of gas for this transaction in wei, defaults to the mean network gas price.</strike>
    24      - `data`: `String` - (optional) Either a [byte string](https://github.com/ethereum/wiki/wiki/Solidity,-Docs-and-ABI) containing the associated data of the message, or in the case of a contract-creation transaction, the initialisation code.
    25      - `nonce`: `Number`  - (optional) Integer of a nonce. This allows to overwrite your own pending transactions that use the same nonce.
    26      - `privateFrom`: `String`  - (optional) When sending a private transaction, the sending party's base64-encoded public key to use. If not present *and* passing `privateFor`, use the default key as configured in the `TransactionManager`.
    27      - `privateFor`: `List<String>`  - (optional) When sending a private transaction, an array of the recipients' base64-encoded public keys.
    28  2. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous.
    29  
    30  ##### Returns
    31  
    32  `String` - The 32 Bytes transaction hash as HEX string.
    33  
    34  If the transaction was a contract creation use `web3.eth.getTransactionReceipt()` to get the contract address, after the transaction was mined.
    35  
    36  ##### Example
    37  
    38  ```js
    39  // compiled solidity source code using https://chriseth.github.io/cpp-ethereum/
    40  var code = "603d80600c6000396000f3007c01000000000000000000000000000000000000000000000000000000006000350463c6888fa18114602d57005b6007600435028060005260206000f3";
    41  
    42  web3.eth.sendTransaction({
    43      data: code,
    44      privateFor: ["ROAZBWtSacxXQrOe3FGAqJDyJjFePR5ce4TSIzmJ0Bc="]
    45    },
    46    function(err, address) {
    47      if (!err) {
    48        console.log(address); // "0x7f9fade1c0d57a7af66ab4ead7c2eb7b11a91385"
    49      }
    50    }
    51  });
    52  ```
    53  ***
    54  
    55  #### eth.sendRawPrivateTransaction
    56  
    57  __To support sending raw transactions in Quorum, the `web3.eth.sendRawPrivateTransaction(string, object)` API method has been created.__
    58  
    59  ```js
    60  web3.eth.sendRawPrivateTransaction(signedTransactionData [, privateData] [, callback])
    61  ```
    62  
    63  Sends a pre-signed transaction. For example can be signed using: https://github.com/SilentCicero/ethereumjs-accounts
    64  
    65  __Important:__ Please note that before calling this API, a `storeraw` api need to be called first to Quorum's private transaction manager. Instructions on how to do this can be found [here](../../Privacy/Tessera/Usage/Interface%20&%20API/).
    66  
    67  ##### Parameters
    68   1. `String` - Signed transaction data in HEX format
    69   2. `Object` - Private data to send
    70      - `privateFor`: `List<String>`  - When sending a private transaction, an array of the recipients' base64-encoded public keys.
    71  3. `Function` - (optional) If you pass a callback the HTTP request is made asynchronous.
    72  
    73  ##### Returns
    74   `String` - The 32 Bytes transaction hash as HEX string.
    75   If the transaction was a contract creation use `web3.eth.getTransactionReceipt()` to get the contract address, after the transaction was mined.
    76   
    77   
    78  ##### Example
    79  
    80  ```js
    81   var Tx = require('ethereumjs-tx');
    82   var privateKey = new Buffer('e331b6d69882b4cb4ea581d88e0b604039a3de5967688d3dcffdd2270c0fd109', 'hex')
    83    var rawTx = {
    84     nonce: '0x00',
    85     gasPrice: '0x09184e72a000', 
    86     gasLimit: '0x2710',
    87     to: '0x0000000000000000000000000000000000000000', 
    88     value: '0x00', 
    89     // This data should be the hex value of the hash returned by Quorum's privacy transaction manager after invoking storeraw api
    90     data: '0x7f7465737432000000000000000000000000000000000000000000000000000000600057'
    91   }
    92    var tx = new Tx(rawTx);
    93   tx.sign(privateKey);
    94    var serializedTx = tx.serialize();
    95    //console.log(serializedTx.toString('hex'));
    96   //f889808609184e72a00082271094000000000000000000000000000000000000000080a47f74657374320000000000000000000000000000000000000000000000000000006000571ca08a8bbf888cfa37bbf0bb965423625641fc956967b81d12e23709cead01446075a01ce999b56a8a88504be365442ea61239198e23d1fce7d00fcfc5cd3b44b7215f
    97    web3.eth.sendRawPrivateTransaction('0x' + serializedTx.toString('hex'), {privateFor: ["ROAZBWtSacxXQrOe3FGAqJDyJjFePR5ce4TSIzmJ0Bc="]}, function(err, hash) {
    98     if (!err)
    99       console.log(hash); // "0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385"
   100   });
   101  ```
   102   
   103   
   104  
   105  ## JSON RPC Privacy API Reference
   106  
   107  __In addition to the JSON-RPC provided by Ethereum, Quorum exposes below two API calls.__
   108  
   109  
   110  #### eth_storageRoot
   111  
   112  Returns the storage root of given address (Contract/Account etc)
   113  
   114  ##### Parameters
   115  
   116  1. `address`: `String` - The address to fetch the storage root for in hex
   117  2. `block`: `String` - (optional) The block number to look at in hex (e.g. `0x15` for block 21). Uses the latest block if not specified. 
   118  
   119  ##### Returns
   120  
   121  `String` - 32 Bytes storageroot hash as HEX string at latest block height. When blocknumber is given, it provides the storageroot hash at that block height. 
   122  
   123  ##### Example
   124  
   125  ```js
   126  // Request
   127  
   128  curl -X POST http://127.0.0.1:22000 --data '{"jsonrpc": "2.0", "method": "eth_storageRoot", "params":["0x1349f3e1b8d71effb47b840594ff27da7e603d17"], "id": 67}'
   129  
   130  // Response
   131  {
   132    "id":67,
   133    "jsonrpc": "2.0",
   134    "result": "0x81d1fa699f807735499cf6f7df860797cf66f6a66b565cfcda3fae3521eb6861"
   135  }
   136  
   137  ```
   138  
   139  ```js
   140  // When block number is provided...
   141  // Request
   142  
   143  curl -X POST http://127.0.0.1:22000 --data '{"jsonrpc": "2.0", "method": "eth_storageRoot", "params":["0x1349f3e1b8d71effb47b840594ff27da7e603d17","0x1"], "id": 67}'
   144  
   145  // Response
   146  {
   147    "id":67,
   148    "jsonrpc": "2.0",
   149    "result": "0x81d1fa699f807735499cf6f7df860797cf66f6a66b565cfcda3fae3521eb6861"
   150  }
   151  
   152  // After private state of the contract is changed from '42' to '99'
   153  // Request
   154  
   155  curl -X POST http://127.0.0.1:22000 --data '{"jsonrpc": "2.0", "method": "eth_storageRoot", "params":["0x1349f3e1b8d71effb47b840594ff27da7e603d17", "0x2"], "id": 67}'
   156  
   157  // Response
   158  {
   159    "id":67,
   160    "jsonrpc": "2.0",
   161    "result": "0x0edb0e520c35df37a0d080d5245c9b8f9e1f9d7efab77c067d1e12c0a71299da"
   162  }
   163  ```
   164  
   165  ***
   166  
   167  #### eth_getQuorumPayload
   168  
   169  Returns the unencrypted payload from Tessera/constellation
   170  
   171  ##### Parameters
   172  
   173  1. `id`: `String` - the HEX formatted generated Sha3-512 hash of the encrypted payload from the Private Transaction Manager. This is seen in the transaction as the `input` field
   174  
   175  ##### Returns
   176  
   177  `String` - unencrypted transaction payload in HEX format.
   178  
   179  ##### Example
   180  
   181  ```js
   182  // Request
   183  
   184  curl -X POST http://127.0.0.1:22000 --data '{"jsonrpc":"2.0", "method":"eth_getQuorumPayload", "params":["0x5e902fa2af51b186468df6ffc21fd2c26235f4959bf900fc48c17dc1774d86d046c0e466230225845ddf2cf98f23ede5221c935aac27476e77b16604024bade0"], "id":67}'
   185  
   186  // Response
   187  {
   188    "id":67,
   189    "jsonrpc": "2.0",
   190    "result": "0x6060604052341561000f57600080fd5b604051602080610149833981016040528080519060200190919050505b806000819055505b505b610104806100456000396000f30060606040526000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff1680632a1afcd914605157806360fe47b11460775780636d4ce63c146097575b600080fd5b3415605b57600080fd5b606160bd565b6040518082815260200191505060405180910390f35b3415608157600080fd5b6095600480803590602001909190505060c3565b005b341560a157600080fd5b60a760ce565b6040518082815260200191505060405180910390f35b60005481565b806000819055505b50565b6000805490505b905600a165627a7a72305820d5851baab720bba574474de3d09dbeaabc674a15f4dd93b974908476542c23f00029000000000000000000000000000000000000000000000000000000000000002a"
   191  }
   192  
   193  // On a node which is not party to the transaction
   194  // Response
   195  {
   196    "id":67,
   197    "jsonrpc": "2.0",
   198    "result": "0x"
   199  }
   200  ```
   201  
   202  ***
   203  
   204  #### eth_sendTransactionAsync
   205   
   206   Sends a transaction to the network asynchronously. This will return 
   207   immediately, potentially before the transaction has been submitted to the 
   208   transaction pool. A callback can be provided to receive the result of 
   209   submitting the transaction; a server must be set up to receive POST requests
   210   at the given URL.
   211   
   212  ##### Parameters
   213   
   214   1. `Object` - The transaction object to send:
   215       - `from`: `String` - The address for the sending account. Uses the `web3.eth.defaultAccount` property, if not specified.
   216       - `to`: `String` - (optional) The destination address of the message, left undefined for a contract-creation transaction.
   217       - `value`: `Number|String|BigNumber` - (optional) The value transferred for the transaction in Wei, also the endowment if it's a contract-creation transaction.
   218       - `gas`: `Number|String|BigNumber` - (optional, default: To-Be-Determined) The amount of gas to use for the transaction (unused gas is refunded).
   219       - <strike>`gasPrice`: `Number|String|BigNumber` - (optional, default: To-Be-Determined) The price of gas for this transaction in wei, defaults to the mean network gas price.</strike>
   220       - `data`: `String` - (optional) Either a [byte string](https://github.com/ethereum/wiki/wiki/Solidity,-Docs-and-ABI) containing the associated data of the message, or in the case of a contract-creation transaction, the initialisation code.
   221       - `nonce`: `Number`  - (optional) Integer of a nonce. This allows to overwrite your own pending transactions that use the same nonce.
   222       - `privateFrom`: `String`  - (optional) When sending a private transaction, the sending party's base64-encoded public key to use. If not present *and* passing `privateFor`, use the default key as configured in the `TransactionManager`.
   223       - `privateFor`: `List<String>`  - (optional) When sending a private transaction, an array of the recipients' base64-encoded public keys.
   224       - `callbackUrl`: `String` - (optional) the URL to perform a POST request to to post the result of submitted the transaction
   225   
   226  ##### Returns
   227   
   228   1. `String` - The empty hash, defined as `0x0000000000000000000000000000000000000000000000000000000000000000`
   229   
   230   The callback URL receives the following object:
   231   
   232   2. `Object` - The result object:
   233      - `id`: `String` - the identifier in the original RPC call, used to match this result to the request
   234      - `txHash`: `String` - the transaction hash that was generated, if successful
   235      - `error`: `String` - the error that occurred whilst submitting the transaction.
   236   
   237   If the transaction was a contract creation use `web3.eth.getTransactionReceipt()` to get the contract address, after the transaction was mined.
   238   
   239  ##### Example
   240  
   241  For the RPC call and the immediate response:
   242  
   243  ```
   244  // Request
   245  curl -X POST http://127.0.0.1:22000 --data '{"jsonrpc":"2.0", "method":"eth_sendTransactionAsync", "params":[{"from":"0xed9d02e382b34818e88b88a309c7fe71e65f419d", "data": "0x6060604052341561000f57600080fd5b604051602080610149833981016040528080519060200190919050505b806000819055505b505b610104806100456000396000f30060606040526000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff1680632a1afcd914605157806360fe47b11460775780636d4ce63c146097575b600080fd5b3415605b57600080fd5b606160bd565b6040518082815260200191505060405180910390f35b3415608157600080fd5b6095600480803590602001909190505060c3565b005b341560a157600080fd5b60a760ce565b6040518082815260200191505060405180910390f35b60005481565b806000819055505b50565b6000805490505b905600a165627a7a72305820d5851baab720bba574474de3d09dbeaabc674a15f4dd93b974908476542c23f00029000000000000000000000000000000000000000000000000000000000000002a", "gas": "0x47b760", "privateFor": ["ROAZBWtSacxXQrOe3FGAqJDyJjFePR5ce4TSIzmJ0Bc="]}], "id":67}'
   246  
   247  // Response
   248  {
   249    "id": 67,
   250    "jsonrpc": "2.0",
   251    "result": "0x0000000000000000000000000000000000000000000000000000000000000000"
   252  }
   253  
   254  
   255  // Request
   256  curl -X POST http://127.0.0.1:22000 --data '{"jsonrpc":"2.0", "method":"eth_sendTransactionAsync", "params":[{"from":"0xe2e382b3b8871e65f419d", "data": "0x6060604052341561000f57600080fd5b604051602080610149833981016040528080519060200190919050505b806000819055505b505b610104806100456000396000f30060606040526000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff1680632a1afcd914605157806360fe47b11460775780636d4ce63c146097575b600080fd5b3415605b57600080fd5b606160bd565b6040518082815260200191505060405180910390f35b3415608157600080fd5b6095600480803590602001909190505060c3565b005b341560a157600080fd5b60a760ce565b6040518082815260200191505060405180910390f35b60005481565b806000819055505b50565b6000805490505b905600a165627a7a72305820d5851baab720bba574474de3d09dbeaabc674a15f4dd93b974908476542c23f00029000000000000000000000000000000000000000000000000000000000000002a", "gas": "0x47b760", "privateFor": ["ROAZBWtSacxXQrOe3FGAqJDyJjFePR5ce4TSIzmJ0Bc="]}], "id":67}'
   257  
   258  //If a syntactic error occured with the RPC call. 
   259  //In this example the wallet address is the wrong length
   260  //so the error is it cannot convert the parameter to the correct type
   261  //it is NOT an error relating the the address not being managed by this node.
   262  
   263  //Response
   264  {
   265      "id": 67,
   266      "jsonrpc": "2.0",
   267      "error": {
   268          "code": -32602,
   269          "message": "invalid argument 0: json: cannot unmarshal hex string of odd length into Go struct field AsyncSendTxArgs.from of type common.Address"
   270      }
   271  }
   272  ```
   273  
   274  If the callback URL is provided, the following response will be received after
   275  the transaction has been submitted; this example assumes a webserver that can
   276  be accessed by calling http://localhost:8080 has been set up to accept POST 
   277  requests:
   278  
   279  ```
   280  
   281  
   282  // Request
   283  curl -X POST http://127.0.0.1:22000 --data '{"jsonrpc":"2.0", "method":"eth_sendTransactionAsync", "params":[{"from":"0xed9d02e382b34818e88b88a309c7fe71e65f419d", "data": "0x6060604052341561000f57600080fd5b604051602080610149833981016040528080519060200190919050505b806000819055505b505b610104806100456000396000f30060606040526000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff1680632a1afcd914605157806360fe47b11460775780636d4ce63c146097575b600080fd5b3415605b57600080fd5b606160bd565b6040518082815260200191505060405180910390f35b3415608157600080fd5b6095600480803590602001909190505060c3565b005b341560a157600080fd5b60a760ce565b6040518082815260200191505060405180910390f35b60005481565b806000819055505b50565b6000805490505b905600a165627a7a72305820d5851baab720bba574474de3d09dbeaabc674a15f4dd93b974908476542c23f00029000000000000000000000000000000000000000000000000000000000000002a", "gas": "0x47b760", "privateFor": ["ROAZBWtSacxXQrOe3FGAqJDyJjFePR5ce4TSIzmJ0Bc="], "callbackUrl": "http://localhost:8080"}], "id":67}'
   284  
   285  // Response
   286  //Note that the ID is the same in the callback as the request - this can be used to match the request to the response.
   287  {
   288    "id": 67,
   289    "txHash": "0x75ebbf4fbe29355fc8a4b8d1e14ecddf0228b64ef41e6d2fce56047650e2bf17"
   290  }
   291  
   292  
   293  
   294  
   295  // Request
   296  curl -X POST http://127.0.0.1:22000 --data '{"jsonrpc":"2.0", "method":"eth_sendTransactionAsync", "params":[{"from":"0xae9bc6cd5145e67fbd1887a5145271fd182f0ee7", "callbackUrl": "http://localhost:8080", "data": "0x6060604052341561000f57600080fd5b604051602080610149833981016040528080519060200190919050505b806000819055505b505b610104806100456000396000f30060606040526000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff1680632a1afcd914605157806360fe47b11460775780636d4ce63c146097575b600080fd5b3415605b57600080fd5b606160bd565b6040518082815260200191505060405180910390f35b3415608157600080fd5b6095600480803590602001909190505060c3565b005b341560a157600080fd5b60a760ce565b6040518082815260200191505060405180910390f35b60005481565b806000819055505b50565b6000805490505b905600a165627a7a72305820d5851baab720bba574474de3d09dbeaabc674a15f4dd93b974908476542c23f00029000000000000000000000000000000000000000000000000000000000000002a", "gas": "0x47b760", "privateFor": ["ROAZBWtSacxXQrOe3FGAqJDyJjFePR5ce4TSIzmJ0Bc="]}], "id":67}'
   297  
   298  //If a semantic error occured with the RPC call. 
   299  //In this example the wallet address is not managed by the node
   300  //So the RPC call will succeed (giving the empty hash), but the callback will show a failure
   301  
   302  // In the callback
   303  {
   304      "id": 67,
   305      "error":"unknown account"
   306  }
   307  ```